home *** CD-ROM | disk | FTP | other *** search
/ ftp.uv.es / 2014.11.ftp.uv.es.tar / ftp.uv.es / pub / mirror / MailDrop / plug-ins / SamplePlugInProjects.hqx / Sample Plug-in Projects / Mail Drop PlugIns.h next >
C/C++ Source or Header  |  1997-01-08  |  15KB  |  379 lines
  1. /*
  2.     Project:    Mail Drop
  3.     Name:        Mail Drop PlugIns.h
  4.     Programmer:    Carl Bell
  5.     Modified:    7-Jan-97
  6.  
  7.     Documentation for writing plug-ins for Mail Drop doesn't exist, because this is still
  8.     being worked on.  Here's an explanation of how things work currently.
  9.     
  10.     Send any questions/comments/complaints to Carl_Bell@baylor.edu.
  11.  
  12.     Mail Drop supports 68K and PPC code resource based plug-ins.  Eventually, "fat" resources
  13.     and shared libraries will also be supported.  For now, plug-ins are "one way", i.e., they
  14.     respond to commands from Mail Drop.  Eventually, there will be some sort of callback
  15.     mechanism so plug-ins can get Mail Drop to do things for them.
  16.  
  17.     At startup (and possibly when opening a prefs file, I can't remember right now) MD searches
  18.     for plug-ins in 4 different folders:
  19.  
  20.         1) a folder in the same folder as Mail Drop    called 'Plug-ins'
  21.         2) a folder in the same folder as Mail Drop called 'Mail Drop Plug-ins'
  22.         3) a folder inside the Extensions folder called 'Mail Drop Plug-ins'
  23.         4) a folder inside the System folder called 'Mail Drop Plug-ins'.
  24.  
  25.     These folders will be searched recursively, so plug-ins can be located within folders
  26.     inside the plug-in folder(s).  Mail Drop looks for files of types 'MDPL' (code resource
  27.     plug-ins) and 'shlb' (shared libraries) and creator 'MDrp' (MD's sig).  You won't be able
  28.     to use your own BNDL resource if you want a different icon; use a custom icon instead.
  29.     Currently, shared libraries ('shlb') are ignored.
  30.  
  31.     Mail Drop searches each 'MDPL' file for a resource of type 'M68K', 'MPPC', and 'MFAT', for
  32.     68K, native PPC, and fat resources respectively.  It searches in order, so if you have both
  33.     a 68K and PPC resource, the PPC resource will be ignored.  Native PPC plug-ins are ignored
  34.     on 68K Macs, but they will be used if you are running the 68K version of Mail Drop on a
  35.     PowerMac.  Fat resources are currently ignored. If you have multiple resources of a particular
  36.     type, the file itself is ignored. In other words, each plug-in file should have one and only
  37.     one code resource in it.  If you want both a 68K and native version of a plug-in, use fat
  38.     (not!) or use two different plug-in files.
  39.  
  40.     Every plug-in must have a "description" resource ('MDPD' ID=128).  This resource specifies
  41.     the plug-in's type (e.g., an address book import plug-in), some flags, the plug-in's name,
  42.     and its "about" string. The plug-in type is one of the 4 byte OSTypes defined below.  Flags
  43.     are currently ignored. The name is a pascal string that is displayed to the user in popup
  44.     menus, etc.  It is not necessarily the same as the plug-in's file's name.  The about string
  45.     is a pascal string displayed in an "about" box.
  46.  
  47.     A plug-in's entry point is defined as:
  48.  
  49.         pascal OSErr main(short selector, MailDropPlugInPBPtr plugInPBPtr, void *plugInData);
  50.  
  51.     selector tells the plug-in what Mail Drop wants it to do
  52.     plugInPBPtr is a pointer to a MailDropPlugInPB paramater block, explained below
  53.     plugInData is a pointer to data "owned" by the plug-in for use as "globals" (not
  54.         implemented yet, so ignore it)
  55.         
  56.     The parameter block is a struct containing:
  57.  
  58.         OSType    type - the type of plugin that Mail Drop thinks it is calling
  59.         FSSpec    spec - a FSSpec of the plug-in's file
  60.         other stuff, depending on the type of plug-in. See below.
  61.  
  62.     Whenever a plug-in is called, it should first check for a nil paramater block and
  63.     an incorrect plug-in type, and return errNullParamBlock or errWrongPlugInType if
  64.     necessary.  Both of these errors would indicate bugs in Mail Drop so they should
  65.     never occur (yeah, right) but it's better to be safe than sorry.
  66.  
  67.     A plug-in is first called by Mail Drop with the selector selectorPrepare. This is where
  68.     the plug-in should do any initialization, set up "globals", etc.  For now, ignore it and
  69.     return noErr.  When Mail Drop is done with the plug-in, it calls it with the selector
  70.     selectorFinish.  The plug-in should clean up after itself, release the "globals", etc.
  71.  
  72.     If a plug-in is called with an invalid selector, e.g., a "Default Info" plug-in getting
  73.     an "Address Book Import" plug-in's selectorImportSetTypeCreator selector, it should return
  74.     errInvalidSelector.  (This would be another bug in Mail Drop...)  If some other error
  75.     occurs, e.g., memFullErr, the plug-in should return that error.
  76.  
  77.     ******************************************************************************************
  78.     
  79.      - "Default Info" plug-ins -
  80.  
  81.     These plug-ins are used by Mail Drop to set the default user, password, and imap server at
  82.     startup.  Although you can (and should) specify the default IMAP server in Mail Drop's internal
  83.     preference resource, this won't work if your site has multiple IMAP servers.  Note that it isn't
  84.     necessary to set all three of these items.  The username and password are really not that much of
  85.     a problem because MD will bring up the login dialog if they aren't available.  Setting the imap
  86.     server requires the user to go into the preferences dialog, which can be a hassle after a while.
  87.     
  88.     This type of plug-in is different that all others because Mail Drop will use the first DefaultInfo
  89.     plug-in that it finds when searching the folders listed above.
  90.  
  91.         Plug-in type:
  92.  
  93.             plugInTypeDefaultInfo = 'Dflt'
  94.  
  95.         Selectors:
  96.  
  97.             selectorDefaultGetInfo    = 100
  98.  
  99.         Extra PB stuff:
  100.  
  101.             char    Username[80];        // These array sizes are not arbitrary but are the current internal
  102.             char    Password[80];        // sizes used in Mail Drop. The strings are null terminated C strings
  103.             char    IMAPServer[256];    // not pascal strings.  Subject to change without notice. :-)
  104.  
  105.     When MD needs the default info, it will call the plug-in with the selector selectorDefaultGetInfo.
  106.     The plug-in should get the information by some method and fill in the character arrays in the
  107.     parameter block.  If the information isn't available, e.g., you don't know the user's password,
  108.     leave the array as is because it has already been "zeroed out".
  109.  
  110.     ******************************************************************************************
  111.     
  112.      - "Address Book Import" plug-ins -
  113.  
  114.     These plug-ins are used by Mail Drop to import addresses into Mail Drop's address book.
  115.     Note that this may very well change in the future as the address book's functionality
  116.     is enhanced, e.g., to allow nicknames, aliases, notes, etc., so any plug-in written may
  117.     have to be rewritten.  Hopefully things will be backwards compatible.
  118.  
  119.         Plug-in type:
  120.         
  121.             plugInAddressImport = 'Impt'
  122.  
  123.         Selectors:
  124.  
  125.             selectorImportSetTypeCreator    = 200,
  126.             selectorImportFile                = 201
  127.  
  128.         Extra PB stuff:
  129.  
  130.             OSType        fileType;        // The type of file that we can import
  131.             OSType        fileCreator;    // The creator of file that we can import
  132.             FSSpec        importFile;        // The file that we want to import
  133.             Handle        addresses;        // The addresses
  134.  
  135.     When the user selects the "Import" menu, MD bring up a standard file open dialog with a
  136.     pop-up menu that has a list of these plug-ins.  MD will call the plug-in with the selector
  137.     selectorImportSetTypeCreator.  If the plug-in only handles a certain type of file it should
  138.     set one or both of the PB's fileType and fileCreator fields.  Mail Drop will only show files
  139.     of this type and/or creator in the standard file open dialog's list.  These fields will
  140.     initially contain '****' which means all files/creators.  If the plug-in doesn't deal with
  141.     specify file types, or files of a particular type but not a creator (e.g., 'TEXT') then
  142.     it should leave one or both these fields as is.  Note that you specifying a fileType as
  143.     '****' and a particular creator will not show all files with that creator as you would
  144.     expect, but would instead show all files, i.e., the creator is ignored.  This may change
  145.     in the future.
  146.     
  147.     When the user has chosen the file to import, Mail Drop will call the plug-in with the
  148.     selector selectorImportFile.  The file's FSSpec will be stored in the importFile field.
  149.     The plug-in should open the file, convert the file's contents into a specific format (as
  150.     detailed below) stored in a handle (the PB's addresses field), and return.  It is the
  151.     plug-in's responsibility to create the addresses handle because it will be nil upon
  152.     entry.  It is also the plug-in's responsibility to dispose the handle when it receives
  153.     the selectorFinish selector.
  154.  
  155.     The converted addresses that are returned are a handle to a block of text that looks
  156.     like the following:
  157.     
  158.     "personal name" <address>
  159.     "personal name" <address>
  160.     <address>
  161.     "personal name" <address>
  162.     "group name" <GROUP@GROUP>
  163.     "personal name" <address>
  164.     <address>
  165.     "personal name" <address>
  166.     etc.
  167.     
  168.     The personal name, if there is one, needs to be in quotes even if there are no special
  169.     characters, e.g., periods.  Each line should end with a CR, not LF or CRLF.  There
  170.     should be a CR at the end of the last address, as well.
  171.  
  172.     Addresses will be added to the main address book until a "group" line, i.e., one that has
  173.     the    GROUP@GROUP address, is reached.  A group called "group name" will be created, if it
  174.     doesn't already exist, and any address following that will be added to that group until
  175.     the next group line is reached.
  176.  
  177.     The following functions can/should be used to "fix" address and name strings before they
  178.     are added to the text block.  The characters below that return false are not permitted
  179.     by Mail Drop and the address will either be ignore by the import function, or the
  180.     invalid characters will be dropped.
  181.     
  182.         Boolean ValidAddressChar(char ch)
  183.         {
  184.             if (ch < 32) return false;
  185.             if (ch == '<') return false;
  186.             if (ch == '>') return false;
  187.             if (ch == '\"') return false;
  188.             if (ch == '\\') return false;
  189.             if (ch == '\'') return false;
  190.             if (ch == ',') return false;
  191.             if (ch >= 127) return false;
  192.             return true;
  193.         }
  194.  
  195.         Boolean ValidRealNameChar(char ch)
  196.         {
  197.             if (ch < 32) return false;
  198.             if (ch == '<') return false;
  199.             if (ch == '>') return false;
  200.             if (ch == '\\') return false;
  201.             if (ch == '(') return false;
  202.             if (ch == ')') return false;
  203.             if (ch == '@') return false;
  204.             if (ch >= 127) return false;    // eventually 8 bit will work but not yet
  205.             return true;
  206.         }    
  207.  
  208.     ******************************************************************************************
  209.  
  210.     That's all folks....
  211.  
  212. */
  213.  
  214. #pragma once
  215.  
  216. #ifndef __MAILDROPPLUGINS__
  217. #define __MAILDROPPLUGINS__
  218.  
  219. #define kPlugInCreator            'MDrp'    // file createor of plugin files (Mail Drop's sig)
  220. #define kPlugInTypeResource        'MDPL'    // file type of plugin resource file
  221. #define kPlugInTypeSharedLib    'shlb'    // file type of plugin shared library file
  222.  
  223. #define kPlugIn68KResType        'M68K'    // resource type of 68K plugin
  224. #define kPlugInPPCResType        'MPPC'    // resource type of native PPC plugin
  225. #define kPlugInFatResType        'MFAT'    // resource type of "fat" plugin
  226.  
  227. #define kPlugInDescResType        'MDPD'    // resource type of plugin description
  228.  
  229. #define kPlugInResourceID        128        // code resource plugins and description resources
  230.                                         // always use res id 128
  231.  
  232. //    These are the possible types of plugins.  The type field in a plugin's MailDropPlugInDesc
  233. //    resource must be one of these.
  234.  
  235. enum {
  236.  
  237.     plugInTypeDefaultInfo    = 'Dflt',    // Used to set default user, password, and imap server at startup
  238.     plugInAddressImport        = 'Impt',    // Import addresses into address book
  239.  
  240.     // These aren't supported yet...
  241.  
  242.     plugInAuthentication    = 'Auth',    // Other IMAP authentication, e.g., kerberos
  243.  
  244.     plugInAddressExport        = 'Expt',    // Export addresses from address book
  245.     plugInAddressSearch        = 'Srch',    // Search for an address, e.g., ph
  246.  
  247.     plugInPreferences        = 'Pref'    // Alternate prefs file method, e.g., ACAP, Internet Config
  248.  
  249. };
  250.  
  251. // Flags - currently ignored :-/
  252.  
  253. #define    plugInFlagUsesFile        0x00000001        // Needs access to its resources
  254. #define    plugInFlagKeepInMemory    0x00000002        // Keep in memory between calls if possible (i.e., may be called often)
  255.  
  256. // Mail Drop plugin Description 'MDPD' resource.
  257.  
  258. //    I think this Rez type declaration is right, but haven't checked it.  There should
  259. //    should be a ResEdit 'TMPL' inside Mail Drop in any case...
  260.  
  261. /*
  262.  
  263. type 'MDPD' {                // Mail Drop Plugin Description resource
  264.  
  265.     literal longint;        // type
  266.     unsigned hex longint;    // flags
  267.     pstring;                // name
  268.     pstring;                // about string
  269. };
  270.  
  271. */
  272.  
  273. // Mail Drop Plugin Parameter blocks and related oddities
  274.  
  275. // #define MailDropParamBlockHeader \
  276.  
  277. struct MailDropDefaultParam {
  278.  
  279.     OSType    type;                // The type of plugin that Mail Drop thinks it is calling
  280.     FSSpec    spec;                // The plugin's home file
  281.  
  282.     char    Username[80];        // These array sizes are not arbitrary but are the current internal
  283.     char    Password[80];        // sizes used in Mail Drop. The strings are null terminated C strings
  284.     char    IMAPServer[256];    // not pascal strings.  Subject to change without notice. :-)
  285. };
  286.  
  287. typedef struct MailDropDefaultParam MailDropDefaultParam, *MailDropDefaultParamPtr;
  288.  
  289. struct MailDropImportParam {
  290.  
  291.     OSType    type;                // The type of plugin that Mail Drop thinks it is calling
  292.     FSSpec    spec;                // The plugin's home file
  293.  
  294.     OSType        fileType;        // The type of file that we can import
  295.     OSType        fileCreator;    // The creator of file that we can import
  296.     FSSpec        importFile;        // The file that we want to import
  297.     Handle        addresses;        // The addresses
  298. };
  299.  
  300. typedef struct MailDropImportParam MailDropImportParam, *MailDropImportParamPtr;
  301.  
  302. struct MailDropCrapolaParam {
  303.  
  304.     OSType    type;                // The type of plugin that Mail Drop thinks it is calling
  305.     FSSpec    spec;                // The plugin's home file
  306.  
  307.     char    crapola[80];
  308. };
  309.  
  310. typedef struct MailDropCrapolaParam MailDropCrapolaParam, *MailDropCrapolaParamPtr;
  311.  
  312. union MailDropPlugInPB {
  313.     MailDropDefaultParam    defaultParam;
  314.     MailDropImportParam        importParam;
  315.     MailDropCrapolaParam    crapolaParam;
  316. };
  317. typedef union MailDropPlugInPB MailDropPlugInPB, *MailDropPlugInPBPtr;
  318.  
  319. // Some error codes 
  320.  
  321. enum {
  322.     errUnknownError            = 1,
  323.     errNullParamBlock        = 2,
  324.     errWrongPlugInType        = 3,
  325.     errInvalidSelector        = 4
  326. };
  327.  
  328. // Selectors
  329.  
  330. enum {
  331.  
  332.     selectorPrepare        = 1,
  333.     selectorFinish        = 2,
  334.  
  335.     selectorDefaultGetInfo    = 100,
  336.  
  337.     selectorImportSetTypeCreator    = 200,
  338.     selectorImportFile                = 201
  339. };
  340.  
  341. typedef pascal OSErr (*MailDropPlugInProc)(short selector, MailDropPlugInPBPtr plugInPBPtr, void *plugInData);
  342.  
  343. enum {
  344.     uppMailDropPlugInProcInfo = kPascalStackBased
  345.         | RESULT_SIZE(SIZE_CODE(sizeof(OSErr)))
  346.         | STACK_ROUTINE_PARAMETER(1, SIZE_CODE(sizeof(short)))
  347.         | STACK_ROUTINE_PARAMETER(2, SIZE_CODE(sizeof(MailDropPlugInPBPtr)))
  348.         | STACK_ROUTINE_PARAMETER(3, SIZE_CODE(sizeof(void *)))
  349. };
  350.  
  351. #if USESROUTINEDESCRIPTORS
  352.  
  353. typedef UniversalProcPtr MailDropPlugInUPP;
  354.  
  355. #define NewMailDropPlugInProc(userRoutine) \
  356.         (MailDropPlugInUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppMailDropPlugInProcInfo, GetCurrentArchitecture())
  357.  
  358. #define NewMailDropPlugInProc68K(userRoutine) \
  359.         (MailDropPlugInUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppMailDropPlugInProcInfo, (ISAType)kM68kISA)
  360.  
  361. #define CallMailDropPlugInProc(userRoutine, selector, plugInPBPtr, plugInData) \
  362.         CallUniversalProc((UniversalProcPtr)(userRoutine), uppMailDropPlugInProcInfo, selector, plugInPBPtr, plugInData)
  363.  
  364. #else
  365.  
  366. typedef MailDropPlugInProc MailDropPlugInUPP;
  367.  
  368. #define NewMailDropPlugInProc(userRoutine) \
  369.         (MailDropPlugInUPP)(userRoutine)
  370.  
  371. #define NewMailDropPlugInProc68K(userRoutine) \
  372.         (MailDropPlugInUPP)(userRoutine)
  373.  
  374. #define CallMailDropPlugInProc(userRoutine, selector, plugInPBPtr, plugInData) \
  375.         (*(userRoutine))(selector, plugInPBPtr, plugInData)
  376.  
  377. #endif // USESROUTINEDESCRIPTORS
  378.  
  379. #endif // __MAILDROPPLUGINS__